<!DOCTYPE html>
<!-- NOTE: Styling is based on the CommonMark specification template:                -->
<!-- - https://github.com/commonmark/commonmark-spec/blob/master/tools/make_spec.lua -->
<!-- - https://github.com/commonmark/commonmark-spec/blob/master/tools/template.html -->
<!--                                                                                 -->
<!-- NOTE: 'TODO:' comments will be followed up as task(s) on this issue:            -->
<!-- - https://gitlab.com/gitlab-org/gitlab/-/issues/361241                          -->
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>GitLab Flavored Markdown Official Specification</title>
  <style type="text/css">
    body {
      font-family: Helvetica, arial, freesans, clean, sans-serif;
      line-height: 1.4;
      max-width: 48em;
      margin: auto;
      padding: 0 0.5em 4em;
      color: #333333;
      background-color: #ffffff;
      font-size: 13pt;
    }

    div#TOC ul { list-style: none; }
    h1 {
      font-size: 140%;
      font-weight: bold;
      border-top: 1px solid gray;
      padding-top: 0.5em;
    }

    h2 {
      font-size: 120%;
      font-weight: bold;
    }

    h3 {
      font-size: 110%;
      font-weight: bold;
    }

    h4 {
      font-size: 100%;
      font-weight: bold;
    }

    /* NOTE: "font-weight: bold" was applied to "a.definition" class in original CommonMark */
    /*       template, but in practice it was applied to all anchors                        */
    a {
      font-weight: bold;
    }


    /* TODO: Format whitespace in examples. This will require preprocessing to insert spans around them. */
    /*span.space { position: relative; }*/
    /*span.space:after {*/
    /*  content: "·";*/
    /*  position: absolute;*/
    /*  !* create a mark that indicates a space (trick from D. Greenspan) *!*/
    /*  top: 0; bottom: 7px; left: 1px; right: 1px;*/
    /*  color: #aaaaaa;*/
    /*}*/
    /*@media print {*/
    /*  a.dingus { display: none; }*/
    /*}*/

    div.example {
      overflow: hidden;
    }

    p {
      text-align: justify;
    }

    pre {
      padding: 0.5em;
      margin: 0.2em 0 0.5em;
      font-size: 88%;
    }

    pre {
      white-space: pre-wrap; /* css-3 */
      white-space: -moz-pre-wrap; /* Mozilla, since 1999 */
      white-space: -o-pre-wrap; /* Opera 7 */
      word-wrap: break-word; /* Internet Explorer 5.5+ */
    }

    code {
      font-family: monospace;
      background-color: #d3e1e4;
    }

    pre > code {
      background-color: transparent;
    }

    .example {
      font-size: 0; /* hack to get width: 50% to work on inline-block */
      padding-bottom: 6pt;
    }

    .column pre {
      font-size: 11pt;
      padding: 2pt 6pt;
    }

    div.examplenum {
      font-size: 11pt;
      text-align: left;
      margin-bottom: 10px;
    }

    div.column {
      display: inline-block;
      width: 50%;
      vertical-align: top;
    }

    div.example > div:nth-child(2) {
      clear: left;
      background-color: #d3e1e4;
    }

    div.example > div:nth-child(3) {
      clear: right;
      background-color: #c9cace;
    }

    @media print {
      @page {
        size: auto;
        margin: 1.2in 1.2in 1.2in 1.2in;
      }

      body {
        margin: 0;
        line-height: 1.2;
        font-size: 10pt;
      }

      .column pre {
        font-size: 9pt;
      }

      div.examplenum {
        font-size: 9pt;
      }
    }
  </style>
  <!-- TODO: Extract this javascript out to a separate file and unit test it -->
  <script type="text/javascript">
    /* NOTE: The following code performs many of the pre-processing steps originally handled */
    /* in https://github.com/commonmark/commonmark-spec/blob/master/tools/make_spec.lua      */

    /* Adds a div.example wrapper around each pair of example code blocks. */
    function addAttributesToExampleWrapperDivs() {
      const exampleAnchorTags = document.querySelectorAll("a[href^=\"#example-\"]");
      for (const exampleAnchorTag of exampleAnchorTags) {
        const examplenumDiv = exampleAnchorTag.parentElement;
        examplenumDiv.classList.add("examplenum");
        const exampleDiv = examplenumDiv.parentElement;
        exampleDiv.classList.add("example");
        exampleDiv.id = exampleAnchorTag.getAttribute("href").substring(1);
      }
    }

    function addColumnClassToMarkdownDivs() {
      const markdownCodeBlockDivs = document.querySelectorAll("div.markdown-code-block");
      for (const markdownCodeBlockDiv of markdownCodeBlockDivs) {
        markdownCodeBlockDiv.classList.add("column");
      }
    }

    function addNumbersToHeaders() {
      const headers = document.querySelectorAll('h1,h2,h3');
      let h1Index = -1; // NOTE: -1 because we don't assign a number to the title
      let h2Index = 0;
      let h3Index = 0;
      const tocEntries = [];
      for (const header of headers) {
        if (h1Index === -1) {
          h1Index++;
          continue;
        }

        const originalHeaderTextContent = header.textContent.trim();
        const headerAnchor = originalHeaderTextContent.toLowerCase().replaceAll(' ', '-');
        header.id = headerAnchor;
        let indent;
        let headerTextContent;
        if (header.tagName === 'H1') {
          h1Index++;
          h2Index = 0;
          h3Index = 0;
          header.textContent = headerTextContent = h1Index + ' ' + originalHeaderTextContent;
          indent = 0;
        } else if (header.tagName === 'H2') {
          h2Index++;
          h3Index = 0;
          header.textContent =
            headerTextContent = h1Index + '.' + h2Index + ' ' + originalHeaderTextContent;
          indent = 1;
        } else if (header.tagName === 'H3') {
          h3Index++;
          header.textContent = headerTextContent =
            h1Index + '.' + h2Index + '.' + h3Index + ' ' + originalHeaderTextContent;
          indent = 2;
        }
        tocEntries.push({headerAnchor, headerTextContent, indent});
      }
    }

    document.addEventListener("DOMContentLoaded", function(_event) {
      addAttributesToExampleWrapperDivs();
      addColumnClassToMarkdownDivs();
      const tocEntries = addNumbersToHeaders();
      addToc(tocEntries);
    });

    /* NOTE: The following code is to support the "Try it" interactive "dingus", which        */
    /*       we do not yet support. But it is being left here for comparison context with the */
    /*       original CommonMark template.                                                    */
    // $$(document).ready(function() {
    //   $$("div.example").each(function(e) {
    //     var t = $$(this).find('code.language-markdown').text();
    //     $$(this).find('a.dingus').click(function(f) {
    //       window.open('/dingus/?text=' +
    //         encodeURIComponent(t.replace(/→/g,"\t")));
    //     });
    //   });
    //   $$("code.language-markdown").dblclick(function(e) { window.open('/dingus/?text=' +
    //     encodeURIComponent($$(this).text()));
    //   });
    // });
  </script>
</head>
<body>
<h1 class="title">GitLab Flavored Markdown Official Specification</h1>
<div class="version">Version alpha</div>

<ul class="section-nav">
<li><a href="#introduction">Introduction</a></li>
<li>
<a href="#gitlab-official-specification-markdown">GitLab Official Specification Markdown</a><ul>
<li><a href="#task-list-items">Task list items</a></li>
<li><a href="#front-matter">Front matter</a></li>
<li><a href="#table-of-contents">Table of contents</a></li>
</ul>
</li>
</ul>
<hr data-sourcepos="3:1-3:3">
<p data-sourcepos="4:1-6:3" dir="auto">title: GitLab Flavored Markdown (GLFM) Spec
version: alpha
...</p>
<h1 data-sourcepos="8:1-8:14" dir="auto">
<a id="user-content-introduction" class="anchor" href="#introduction" aria-hidden="true"></a>Introduction</h1>
<p data-sourcepos="10:1-10:284" dir="auto">GitLab Flavored Markdown (GLFM) extends the <a href="https://spec.commonmark.org/current/" rel="nofollow noreferrer noopener" target="_blank">CommonMark specification</a> and is considered a strict superset of CommonMark. It also incorporates the extensions defined by the <a href="https://github.github.com/gfm/" rel="nofollow noreferrer noopener" target="_blank">GitHub Flavored Markdown specification</a>.</p>
<p data-sourcepos="12:1-12:433" dir="auto">This specification will define the various official extensions that comprise GLFM. These extensions are GitLab independent - they do not require a GitLab server for parsing or interaction. The intent is to provide a specification that can be implemented in standard markdown editors. This includes many of the features listed in <a href="https://docs.gitlab.com/ee/user/markdown.html" rel="nofollow noreferrer noopener" target="_blank">user-facing documentation for GitLab Flavored Markdown</a>.</p>
<p data-sourcepos="14:1-14:69" dir="auto">The CommonMark and GitHub specifications will not be duplicated here.</p>
<p data-sourcepos="16:1-19:75" dir="auto">NOTE: The example numbering in this document does not start at "1", because this official specification
only contains a subset of all the examples which are supported by GitLab Flavored Markdown. See
<a href="https://gitlab.com/gitlab-org/gitlab/-/blob/master/glfm_specification/output_example_snapshots/snapshot_spec.html" rel="nofollow noreferrer noopener" target="_blank"><code>snapshot_spec.html</code></a>
for a complete list of all examples, which are a superset of examples from:</p>
<ul data-sourcepos="21:1-25:0" dir="auto">
<li data-sourcepos="21:1-21:12">CommonMark</li>
<li data-sourcepos="22:1-22:26">GitHub Flavored Markdown</li>
<li data-sourcepos="23:1-23:88">GitLab Flavored Markdown Official Specification (the same ones from this specifiation)</li>
<li data-sourcepos="24:1-25:0">GitLab Flavored Markdown Internal Extensions.</li>
</ul>
<!-- BEGIN TESTS -->
<h1 data-sourcepos="27:1-27:40" dir="auto">
<a id="user-content-gitlab-official-specification-markdown" class="anchor" href="#gitlab-official-specification-markdown" aria-hidden="true"></a>GitLab Official Specification Markdown</h1>
<p data-sourcepos="29:1-31:104" dir="auto">Note: This specification is a work in progress. Only some of the official GLFM extensions
are defined. We will continue to add any additional ones found in the
<a href="https://docs.gitlab.com/ee/user/markdown.html" rel="nofollow noreferrer noopener" target="_blank">user-facing documentation for GitLab Flavored Markdown</a>.</p>
<p data-sourcepos="33:1-34:69" dir="auto">There is currently only this single top-level heading, but the
examples may be split into multiple top-level headings in the future.</p>
<h2 data-sourcepos="36:1-36:18" dir="auto">
<a id="user-content-task-list-items" class="anchor" href="#task-list-items" aria-hidden="true"></a>Task list items</h2>
<p data-sourcepos="38:1-39:117" dir="auto">See
<a href="https://docs.gitlab.com/ee/user/markdown.html#task-lists" rel="nofollow noreferrer noopener" target="_blank">Task lists</a> in the GitLab Flavored Markdown documentation.</p>
<p data-sourcepos="41:1-44:39" dir="auto">Task list items (checkboxes) are defined as a GitHub Flavored Markdown extension in a section above.
GitLab extends the behavior of task list items to support additional features.
Some of these features are in-progress, and should not yet be considered part of the official
GitLab Flavored Markdown specification.</p>
<p data-sourcepos="46:1-46:85" dir="auto">Some of the behavior of task list items is implemented as client-side JavaScript/CSS.</p>
<p data-sourcepos="48:1-48:80" dir="auto">The following are some basic examples; more examples may be added in the future.</p>
<p data-sourcepos="50:1-50:16" dir="auto">Incomplete task:</p>
<div>
<div><a href="#example-674">Example 674</a></div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="55:1-57:32" data-canonical-lang="example" data-lang-params="gitlab" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">- [ ] incomplete</span></code></pre>
<copy-code></copy-code>
</div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="59:1-67:32" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">&lt;ul&gt;</span>
<span id="LC2" class="line" lang="plaintext">&lt;li&gt;</span>
<span id="LC3" class="line" lang="plaintext">&lt;task-button/&gt;</span>
<span id="LC4" class="line" lang="plaintext">&lt;input type="checkbox" disabled/&gt;</span>
<span id="LC5" class="line" lang="plaintext">incomplete</span>
<span id="LC6" class="line" lang="plaintext">&lt;/li&gt;</span>
<span id="LC7" class="line" lang="plaintext">&lt;/ul&gt;</span></code></pre>
<copy-code></copy-code>
</div>
</div>
<p data-sourcepos="70:1-70:15" dir="auto">Completed task:</p>
<div>
<div><a href="#example-675">Example 675</a></div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="75:1-77:32" data-canonical-lang="example" data-lang-params="gitlab" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">- [x] completed</span></code></pre>
<copy-code></copy-code>
</div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="79:1-87:32" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">&lt;ul&gt;</span>
<span id="LC2" class="line" lang="plaintext">&lt;li&gt;</span>
<span id="LC3" class="line" lang="plaintext">&lt;task-button/&gt;</span>
<span id="LC4" class="line" lang="plaintext">&lt;input type="checkbox" checked disabled/&gt;</span>
<span id="LC5" class="line" lang="plaintext">completed</span>
<span id="LC6" class="line" lang="plaintext">&lt;/li&gt;</span>
<span id="LC7" class="line" lang="plaintext">&lt;/ul&gt;</span></code></pre>
<copy-code></copy-code>
</div>
</div>
<p data-sourcepos="90:1-90:18" dir="auto">Inapplicable task:</p>
<div>
<div><a href="#example-676">Example 676</a></div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="95:1-97:32" data-canonical-lang="example" data-lang-params="gitlab" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">- [~] inapplicable</span></code></pre>
<copy-code></copy-code>
</div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="99:1-109:32" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">&lt;ul&gt;</span>
<span id="LC2" class="line" lang="plaintext">&lt;li&gt;</span>
<span id="LC3" class="line" lang="plaintext">&lt;task-button/&gt;</span>
<span id="LC4" class="line" lang="plaintext">&lt;input type="checkbox" data-inapplicable disabled&gt;</span>
<span id="LC5" class="line" lang="plaintext">&lt;s&gt;</span>
<span id="LC6" class="line" lang="plaintext">inapplicable</span>
<span id="LC7" class="line" lang="plaintext">&lt;/s&gt;</span>
<span id="LC8" class="line" lang="plaintext">&lt;/li&gt;</span>
<span id="LC9" class="line" lang="plaintext">&lt;/ul&gt;</span></code></pre>
<copy-code></copy-code>
</div>
</div>
<p data-sourcepos="112:1-113:50" dir="auto">Inapplicable task in a "loose" list. Note that the <code>&lt;del&gt;</code> tag is not applied to the
loose text; it has strikethrough applied with CSS.</p>
<div>
<div><a href="#example-677">Example 677</a></div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="118:1-122:32" data-canonical-lang="example" data-lang-params="gitlab" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">- [~] inapplicable</span>
<span id="LC2" class="line" lang="plaintext"></span>
<span id="LC3" class="line" lang="plaintext">  text in loose list</span></code></pre>
<copy-code></copy-code>
</div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="124:1-139:32" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">&lt;ul&gt;</span>
<span id="LC2" class="line" lang="plaintext">&lt;li&gt;</span>
<span id="LC3" class="line" lang="plaintext">&lt;p&gt;</span>
<span id="LC4" class="line" lang="plaintext">&lt;task-button/&gt;</span>
<span id="LC5" class="line" lang="plaintext">&lt;input type="checkbox" data-inapplicable disabled&gt;</span>
<span id="LC6" class="line" lang="plaintext">&lt;s&gt;</span>
<span id="LC7" class="line" lang="plaintext">inapplicable</span>
<span id="LC8" class="line" lang="plaintext">&lt;/s&gt;</span>
<span id="LC9" class="line" lang="plaintext">&lt;/p&gt;</span>
<span id="LC10" class="line" lang="plaintext">&lt;p&gt;</span>
<span id="LC11" class="line" lang="plaintext">text in loose list</span>
<span id="LC12" class="line" lang="plaintext">&lt;/p&gt;</span>
<span id="LC13" class="line" lang="plaintext">&lt;/li&gt;</span>
<span id="LC14" class="line" lang="plaintext">&lt;/ul&gt;</span></code></pre>
<copy-code></copy-code>
</div>
</div>
<h2 data-sourcepos="142:1-142:15" dir="auto">
<a id="user-content-front-matter" class="anchor" href="#front-matter" aria-hidden="true"></a>Front matter</h2>
<p data-sourcepos="144:1-145:121" dir="auto">See
<a href="https://docs.gitlab.com/ee/user/markdown.html#front-matter" rel="nofollow noreferrer noopener" target="_blank">Front matter</a> in the GitLab Flavored Markdown documentation.</p>
<p data-sourcepos="147:1-148:95" dir="auto">Front matter is metadata included at the beginning of a Markdown document, preceding the content.
This data can be used by static site generators like Jekyll, Hugo, and many other applications.</p>
<p data-sourcepos="150:1-150:18" dir="auto">YAML front matter:</p>
<div>
<div><a href="#example-678">Example 678</a></div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="155:1-159:32" data-canonical-lang="example" data-lang-params="gitlab" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">---</span>
<span id="LC2" class="line" lang="plaintext">title: YAML front matter</span>
<span id="LC3" class="line" lang="plaintext">---</span></code></pre>
<copy-code></copy-code>
</div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="161:1-167:32" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">&lt;pre&gt;</span>
<span id="LC2" class="line" lang="plaintext">&lt;code&gt;</span>
<span id="LC3" class="line" lang="plaintext">title: YAML front matter</span>
<span id="LC4" class="line" lang="plaintext">&lt;/code&gt;</span>
<span id="LC5" class="line" lang="plaintext">&lt;/pre&gt;</span></code></pre>
<copy-code></copy-code>
</div>
</div>
<p data-sourcepos="170:1-170:18" dir="auto">TOML front matter:</p>
<div>
<div><a href="#example-679">Example 679</a></div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="175:1-179:32" data-canonical-lang="example" data-lang-params="gitlab" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">+++</span>
<span id="LC2" class="line" lang="plaintext">title: TOML front matter</span>
<span id="LC3" class="line" lang="plaintext">+++</span></code></pre>
<copy-code></copy-code>
</div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="181:1-187:32" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">&lt;pre&gt;</span>
<span id="LC2" class="line" lang="plaintext">&lt;code&gt;</span>
<span id="LC3" class="line" lang="plaintext">title: TOML front matter</span>
<span id="LC4" class="line" lang="plaintext">&lt;/code&gt;</span>
<span id="LC5" class="line" lang="plaintext">&lt;/pre&gt;</span></code></pre>
<copy-code></copy-code>
</div>
</div>
<p data-sourcepos="190:1-190:18" dir="auto">JSON front matter:</p>
<div>
<div><a href="#example-680">Example 680</a></div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="195:1-201:32" data-canonical-lang="example" data-lang-params="gitlab" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">;;;</span>
<span id="LC2" class="line" lang="plaintext">{</span>
<span id="LC3" class="line" lang="plaintext">  "title": "JSON front matter"</span>
<span id="LC4" class="line" lang="plaintext">}</span>
<span id="LC5" class="line" lang="plaintext">;;;</span></code></pre>
<copy-code></copy-code>
</div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="203:1-211:32" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">&lt;pre&gt;</span>
<span id="LC2" class="line" lang="plaintext">&lt;code&gt;</span>
<span id="LC3" class="line" lang="plaintext">{</span>
<span id="LC4" class="line" lang="plaintext">  "title": "JSON front matter"</span>
<span id="LC5" class="line" lang="plaintext">}</span>
<span id="LC6" class="line" lang="plaintext">&lt;/code&gt;</span>
<span id="LC7" class="line" lang="plaintext">&lt;/pre&gt;</span></code></pre>
<copy-code></copy-code>
</div>
</div>
<p data-sourcepos="214:1-214:66" dir="auto">Front matter blocks should be inserted at the top of the document:</p>
<div>
<div><a href="#example-681">Example 681</a></div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="219:1-225:32" data-canonical-lang="example" data-lang-params="gitlab" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">text</span>
<span id="LC2" class="line" lang="plaintext"></span>
<span id="LC3" class="line" lang="plaintext">---</span>
<span id="LC4" class="line" lang="plaintext">title: YAML front matter</span>
<span id="LC5" class="line" lang="plaintext">---</span></code></pre>
<copy-code></copy-code>
</div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="227:1-231:32" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">&lt;p&gt;text&lt;/p&gt;</span>
<span id="LC2" class="line" lang="plaintext">&lt;hr&gt;</span>
<span id="LC3" class="line" lang="plaintext">&lt;h2&gt;title: YAML front matter&lt;/h2&gt;</span></code></pre>
<copy-code></copy-code>
</div>
</div>
<p data-sourcepos="234:1-234:74" dir="auto">Front matter block delimiters shouldn’t be preceded by space characters:</p>
<div>
<div><a href="#example-682">Example 682</a></div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="239:1-243:32" data-canonical-lang="example" data-lang-params="gitlab" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext"> ---</span>
<span id="LC2" class="line" lang="plaintext">title: YAML front matter</span>
<span id="LC3" class="line" lang="plaintext">---</span></code></pre>
<copy-code></copy-code>
</div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="245:1-248:32" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">&lt;hr&gt;</span>
<span id="LC2" class="line" lang="plaintext">&lt;h2&gt;title: YAML front matter&lt;/h2&gt;</span></code></pre>
<copy-code></copy-code>
</div>
</div>
<h2 data-sourcepos="251:1-251:20" dir="auto">
<a id="user-content-table-of-contents" class="anchor" href="#table-of-contents" aria-hidden="true"></a>Table of contents</h2>
<p data-sourcepos="253:1-255:46" dir="auto">See
<a href="https://docs.gitlab.com/ee/user/markdown.html#table-of-contents" rel="nofollow noreferrer noopener" target="_blank">table of contents</a>
in the GitLab Flavored Markdown documentation.</p>
<p data-sourcepos="257:1-261:23" dir="auto">NOTE: Because of this bug (<a href="https://gitlab.com/gitlab-org/gitlab/-/issues/359077" rel="nofollow noreferrer noopener" target="_blank">https://gitlab.com/gitlab-org/gitlab/-/issues/359077</a>),
we cannot actually include the <code>TOC</code> tag with single brackets in backticks
in this Markdown document, otherwise it would render a table of contents inline
right here. So, it's been switched to <code>[</code> + <code>TOC</code> + <code>]</code> instead. This can be reverted
once that bug is fixed.</p>
<p data-sourcepos="263:1-264:76" dir="auto">A table of contents is an unordered list that links to subheadings in the document.
Add either the <code>[[_TOC_]]</code> tag or the <code>[</code> + <code>TOC</code> + <code>]</code> tag on its own line.</p>
<div>
<div><a href="#example-683">Example 683</a></div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="269:1-275:32" data-canonical-lang="example" data-lang-params="gitlab" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">[TOC]</span>
<span id="LC2" class="line" lang="plaintext"></span>
<span id="LC3" class="line" lang="plaintext"># Heading 1</span>
<span id="LC4" class="line" lang="plaintext"></span>
<span id="LC5" class="line" lang="plaintext">## Heading 2</span></code></pre>
<copy-code></copy-code>
</div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="277:1-288:32" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">&lt;nav&gt;</span>
<span id="LC2" class="line" lang="plaintext">  &lt;ul&gt;</span>
<span id="LC3" class="line" lang="plaintext">    &lt;li&gt;&lt;a href="#heading-1"&gt;Heading 1&lt;/a&gt;&lt;/li&gt;</span>
<span id="LC4" class="line" lang="plaintext">    &lt;ul&gt;</span>
<span id="LC5" class="line" lang="plaintext">      &lt;li&gt;&lt;a href="#heading-2"&gt;Heading 2&lt;/a&gt;&lt;/li&gt;</span>
<span id="LC6" class="line" lang="plaintext">    &lt;/ul&gt;</span>
<span id="LC7" class="line" lang="plaintext">  &lt;/ul&gt;</span>
<span id="LC8" class="line" lang="plaintext">&lt;/nav&gt;</span>
<span id="LC9" class="line" lang="plaintext">&lt;h1&gt;Heading 1&lt;/h1&gt;</span>
<span id="LC10" class="line" lang="plaintext">&lt;h2&gt;Heading 2&lt;/h2&gt;</span></code></pre>
<copy-code></copy-code>
</div>
</div>
<div>
<div><a href="#example-684">Example 684</a></div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="294:1-300:32" data-canonical-lang="example" data-lang-params="gitlab" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">[[_TOC_]]</span>
<span id="LC2" class="line" lang="plaintext"></span>
<span id="LC3" class="line" lang="plaintext"># Heading 1</span>
<span id="LC4" class="line" lang="plaintext"></span>
<span id="LC5" class="line" lang="plaintext">## Heading 2</span></code></pre>
<copy-code></copy-code>
</div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="302:1-313:32" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">&lt;nav&gt;</span>
<span id="LC2" class="line" lang="plaintext">  &lt;ul&gt;</span>
<span id="LC3" class="line" lang="plaintext">    &lt;li&gt;&lt;a href="#heading-1"&gt;Heading 1&lt;/a&gt;&lt;/li&gt;</span>
<span id="LC4" class="line" lang="plaintext">    &lt;ul&gt;</span>
<span id="LC5" class="line" lang="plaintext">      &lt;li&gt;&lt;a href="#heading-2"&gt;Heading 2&lt;/a&gt;&lt;/li&gt;</span>
<span id="LC6" class="line" lang="plaintext">    &lt;/ul&gt;</span>
<span id="LC7" class="line" lang="plaintext">  &lt;/ul&gt;</span>
<span id="LC8" class="line" lang="plaintext">&lt;/nav&gt;</span>
<span id="LC9" class="line" lang="plaintext">&lt;h1&gt;Heading 1&lt;/h1&gt;</span>
<span id="LC10" class="line" lang="plaintext">&lt;h2&gt;Heading 2&lt;/h2&gt;</span></code></pre>
<copy-code></copy-code>
</div>
</div>
<p data-sourcepos="316:1-317:5" dir="auto">A table of contents is a block element. It should preceded and followed by a blank
line.</p>
<div>
<div><a href="#example-685">Example 685</a></div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="322:1-328:32" data-canonical-lang="example" data-lang-params="gitlab" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">[[_TOC_]]</span>
<span id="LC2" class="line" lang="plaintext">text</span>
<span id="LC3" class="line" lang="plaintext"></span>
<span id="LC4" class="line" lang="plaintext">text</span>
<span id="LC5" class="line" lang="plaintext">[TOC]</span></code></pre>
<copy-code></copy-code>
</div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="330:1-333:32" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">&lt;p&gt;[[&lt;em&gt;TOC&lt;/em&gt;]]text&lt;/p&gt;</span>
<span id="LC2" class="line" lang="plaintext">&lt;p&gt;text[TOC]&lt;/p&gt;</span></code></pre>
<copy-code></copy-code>
</div>
</div>
<p data-sourcepos="336:1-336:60" dir="auto">A table of contents can be indented with up to three spaces.</p>
<div>
<div><a href="#example-686">Example 686</a></div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="341:1-345:32" data-canonical-lang="example" data-lang-params="gitlab" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">   [[_TOC_]]</span>
<span id="LC2" class="line" lang="plaintext"></span>
<span id="LC3" class="line" lang="plaintext"># Heading 1</span></code></pre>
<copy-code></copy-code>
</div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="347:1-354:32" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">&lt;nav&gt;</span>
<span id="LC2" class="line" lang="plaintext">  &lt;ul&gt;</span>
<span id="LC3" class="line" lang="plaintext">    &lt;li&gt;&lt;a href="#heading-1"&gt;Heading 1&lt;/a&gt;&lt;/li&gt;</span>
<span id="LC4" class="line" lang="plaintext">  &lt;/ul&gt;</span>
<span id="LC5" class="line" lang="plaintext">&lt;/nav&gt;</span>
<span id="LC6" class="line" lang="plaintext">&lt;h1&gt;Heading 1&lt;/h1&gt;</span></code></pre>
<copy-code></copy-code>
</div>
</div>
<!-- END TESTS -->

</body>
</html>

